Add manual entry for treesit-primary-parser

* doc/lispref/parsing.texi (Multiple Languages): Add entry.
* etc/NEWS (Example): Add news.

diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index 645aad94a639beccdb2ddc9adf34b42fbbe8c07f..c8c2fe80c03b2db5c74c513f6ff53ad13191b5fa 100644 (file)
--- a/doc/lispref/parsing.texi
+++ b/doc/lispref/parsing.texi
@@ -1683,16 +1683,34 @@ instead to specify regions of buffer text (i.e., ranges) in which a
 parser will operate.  This section describes functions for setting and
 getting ranges for a parser.
 
+@cindex primary parser
+Generally when there are multiple languages at play, there is a
+``primary'', or ``host'' language.  The parser for this language---the
+@dfn{primary parser}, parses the entire buffer.  Parsers for other
+languages are ``embedded'' or ``guest'' parsers, which only work on part
+of the buffer.  The parse tree of the primary parser is usually used to
+determine the ranges in which the embedded parsers operate.
+
+@vindex treesit-primary-parser
+Major modes should set @var{treesit-primary-parser} to the primary
+parser before calling @code{treesit-major-mode-setup}, so that Emacs can
+configure the primary parser correctly for font-lock and other features.
+
 Lisp programs should call @code{treesit-update-ranges} to make sure
 the ranges for each parser are correct before using parsers in a
 buffer, and call @code{treesit-language-at} to figure out the language
 responsible for the text at some position.  These two functions don't
 work by themselves, they need major modes to set
-@code{treesit-range-settings} and
-@code{treesit-language-at-point-function}, which do the actual work.
+@var{treesit-range-settings} and
+@var{treesit-language-at-point-function}, which do the actual work.
 These functions and variables are explained in more detail towards the
 end of the section.
 
+@b{In short}, multi-language major modes should set
+@var{treesit-primary-parser}, @var{treesit-range-settings}, and
+@var{treesit-language-at-point-function} before calling
+@code{treesit-major-mode-setup}.
+
 @heading Getting and setting ranges
 
 @defun treesit-parser-set-included-ranges parser ranges

diff --git a/etc/NEWS b/etc/NEWS
index 3220a3f16e496c7faa515038e1b62316003fdf2e..922721f143c5efea50e286fca1fefc32fd31d6ef 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2872,6 +2872,12 @@ only return parsers for that language.  If TAG is given, only return
 parsers with that tag.  Note that passing nil as tag doesn't mean return
 all parsers, but rather "all parsers with no tags".
 
++++
+*** New variable 'treesit-primary-parser'.
+This variable should be set by multi-langauge major modes before calling
+'treesit-major-mode-setup', in order for tree-sitter integration
+functionalities to operate correctly.
+
 \f
 * Changes in Emacs 30.1 on Non-Free Operating Systems